<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8">
	<title>File Class - Usage - Fuel Documentation</title>
	<link href="../../assets/css/main.css" media="screen" rel="stylesheet" />
	<script type="text/javascript" src="../../assets/js/jquery-1.4.4.min.js"></script>
	<script type="text/javascript" src="../../assets/js/nav.js"></script>
	<script type="text/javascript" src="../../assets/js/highlight.pack.js"></script>
	<script type="text/javascript">
		$(function() {
			show_nav('classes', '../../');
		});
		hljs.tabReplace = '    ';
		hljs.initHighlightingOnLoad();
	</script>
</head>
<body>

	<header>
		<h1>FUEL Documentation</h1>
	</header>

	<div id="main-nav"></div>

	<section id="content">
		<h2>File Class</h2>

		<p>The file class offers a set of methods to working with files &amp; directories. This can be done through
		some helper methods or through a more advanced object oriented method where all files and directories are
		wrapped in objects.</p>

		<section>
			<h2>Usage</h2>

			<p>The File class's basic usage it through its helper methods which are listed below.</p>
		</section>

		<article>
			<h4>create($basepath, $name, $contents = null, $area = null)</h4>
			<p>Create a file.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$basepath</kbd></th>
								<td><i>required</i></td>
								<td>Location to create the new file in</td>
							</tr>
							<tr>
								<th><kbd>$name</kbd></th>
								<td><i>required</i></td>
								<td>Filename for the new file</td>
							</tr>
							<tr>
								<th><kbd>$contents</kbd></th>
								<td><kbd>null</kbd></td>
								<td>What to put into the new file</td>
							</tr>
							<tr>
								<th><kbd>$area</kbd></th>
								<td><kbd>null</kbd></td>
								<td>Area object to use, defaults to main config (see <a href="advanced.html">advanced
								usage</a> for more information)</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td><kbd>true</kbd></td>
				</tr>
				<tr>
					<th>Throws</th>
					<td><kbd>File_Exception</kbd> when creation fails</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>File::create(DOCROOT, 'test.txt', 'Contents for file.');</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4>create_dir($basepath, $name, $chmod = 0777, $area = null)</h4>
			<p>Create a directory.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$basepath</kbd></th>
								<td><i>required</i></td>
								<td>Location to create the new directory in</td>
							</tr>
							<tr>
								<th><kbd>$name</kbd></th>
								<td><i>required</i></td>
								<td>Name for the new directory</td>
							</tr>
							<tr>
								<th><kbd>$chmod</kbd></th>
								<td><kbd>null</kbd></td>
								<td>Rights for the new directory</td>
							</tr>
							<tr>
								<th><kbd>$area</kbd></th>
								<td><kbd>null</kbd></td>
								<td>Area object to use, defaults to main config (see <a href="advanced.html">advanced
								usage</a> for more information)</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>bool - the output of the mkdir() PHP function</td>
				</tr>
				<tr>
					<th>Throws</th>
					<td><kbd>File_Exception</kbd> when creation fails</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>File::create(DOCROOT, 'test', 0755);</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4>read($path, $as_string = false, $area = null)</h4>
			<p>Reads a file.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$path</kbd></th>
								<td><i>required</i></td>
								<td>Location of the file to read</td>
							</tr>
							<tr>
								<th><kbd>$as_string</kbd></th>
								<td><kbd>false</kbd></td>
								<td>Makes it use readfile() on false or file_get_contents() on true</td>
							</tr>
							<tr>
								<th><kbd>$area</kbd></th>
								<td><kbd>null</kbd></td>
								<td>Area object to use, defaults to main config (see <a href="advanced.html">advanced
								usage</a> for more information)</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>int|string - returns the number of bytes when $as_string was set to false or the file's contents
					as a string when it was set to true.</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>// Returns 'Contents for file.' if you created the file in the example for File::create()
File::read(DOCROOT.'test.txt', true);</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4>read_dir($path, $depth = 0, $filter = null, $area = null)</h4>
			<p>Reads directory contents into an array.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$path</kbd></th>
								<td><i>required</i></td>
								<td>Location of the directory to read</td>
							</tr>
							<tr>
								<th><kbd>$depth</kbd></th>
								<td><kbd>0</kbd></td>
								<td>How deep the subdirectories are recursed: 0 for unlimited, 1 for only the current
								directory or specific number.</td>
							</tr>
							<tr>
								<th><kbd>$filter</kbd></th>
								<td><kbd>null</kbd></td>
								<td>A filter for which files to read: <kbd>array()</kbd> for all or <kbd>null</kbd> for
								all but hidden.</td>
							</tr>
							<tr>
								<th><kbd>$area</kbd></th>
								<td><kbd>null</kbd></td>
								<td>Area object to use, defaults to main config (see <a href="advanced.html">advanced
								usage</a> for more information)</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td>array - a natural-case sorted array with subdirectories on top. Directories have a string key
					with array value (or false when not read because of $depth limitation) and files are int indexed
					with filename as value.</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>File::read(DOCROOT);</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4>update($basepath, $name, $contents = null, $area = null)</h4>
			<p>Updates a file.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$basepath</kbd></th>
								<td><i>required</i></td>
								<td>Location of the file to update</td>
							</tr>
							<tr>
								<th><kbd>$name</kbd></th>
								<td><i>required</i></td>
								<td>Filename for the file. If it does not exist, it will be created</td>
							</tr>
							<tr>
								<th><kbd>$contents</kbd></th>
								<td><kbd>null</kbd></td>
								<td>What to put into the file</td>
							</tr>
							<tr>
								<th><kbd>$area</kbd></th>
								<td><kbd>null</kbd></td>
								<td>Area object to use, defaults to main config (see <a href="advanced.html">advanced
								usage</a> for more information)</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td><kbd>true</kbd></td>
				</tr>
				<tr>
					<th>Throws</th>
					<td><kbd>File_Exception</kbd> when creation fails</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>File::update(DOCROOT, 'test.txt', 'New contents for file.');</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

		<article>
			<h4>append($basepath, $name, $contents = null, $area = null)</h4>
			<p>Appends to an existing file.</p>
			<table class="method">
				<tbody>
				<tr>
					<th class="legend">Static</th>
					<td>Yes</td>
				</tr>
				<tr>
					<th>Parameters</th>
					<td>
						<table class="parameters">
							<tr>
								<th>Param</th>
								<th>Default</th>
								<th class="description">Description</th>
							</tr>
							<tr>
								<th><kbd>$basepath</kbd></th>
								<td><i>required</i></td>
								<td>Location of the file to append to</td>
							</tr>
							<tr>
								<th><kbd>$name</kbd></th>
								<td><i>required</i></td>
								<td>Filename for the file. This file has to exist</td>
							</tr>
							<tr>
								<th><kbd>$contents</kbd></th>
								<td><kbd>null</kbd></td>
								<td>What to add to the file</td>
							</tr>
							<tr>
								<th><kbd>$area</kbd></th>
								<td><kbd>null</kbd></td>
								<td>Area object to use, defaults to main config (see <a href="advanced.html">advanced
								usage</a> for more information)</td>
							</tr>
						</table>
					</td>
				</tr>
				<tr>
					<th>Returns</th>
					<td><kbd>true</kbd></td>
				</tr>
				<tr>
					<th>Throws</th>
					<td><kbd>File_Exception</kbd> when the file does not exist</td>
				</tr>
				<tr>
					<th>Example</th>
					<td>
						<pre class="php"><code>File::append(DOCROOT, 'test.txt', 'Additional contents for file.');</code></pre>
					</td>
				</tr>
				</tbody>
			</table>
		</article>

	</section>

	<section id="footer">
		<p>
			<a href="http://fuelphp.com">Fuel PHP</a> is released under the MIT license.<br />
			&copy; 2010 - 2011 Fuel Development Team
		</p>
	</section>

</body>
</html>
